---
title: Installation
description: Get started with HeroUI in the official documentation, and learn more about all our features!
---

# Installation

Requirements:

- [React 18](https://reactjs.org/) or later
- [Tailwind CSS v4](https://tailwindcss.com)
- [Framer Motion 11.9](https://www.framer.com/motion/) or later

---

<CarbonAd/>

## Automatic Installation

Using the CLI is now the easiest way to start a HeroUI project. You can initialize your project and add components directly via the CLI:

<Steps>

### Installation 
Execute one of the following commands in your terminal:
<PackageManagers
  commands={{
    npm: "npm install -g heroui-cli",
    yarn: "yarn global add heroui-cli",
    pnpm: "pnpm add -g heroui-cli",
    bun: "bun add -g heroui-cli",
  }}
/>

### Initialization and Starting the App
Initialize the project by using the `init` command. 
```bash
heroui init my-heroui-app
```

You will be prompted to configure your project:

```bash
◇  Select a template (Enter to select)
│  ● App (A Next.js 14 with app directory template pre-configured with HeroUI (v2) and Tailwind CSS.)
│  ○ Pages (A Next.js 14 with pages directory template pre-configured with HeroUI (v2) and Tailwind CSS.)
│  ○ Vite (A Vite template pre-configured with HeroUI (v2) and Tailwind CSS.)
```

Install the dependencies to start the local server:
<PackageManagers
  commands={{
    npm: "cd my-heroui-app && npm install",
    yarn: "cd my-heroui-app && yarn install",
    pnpm: "cd my-heroui-app && pnpm install",
    bun: "cd my-heroui-app && bun install",
  }}
/>

Start the local server:
<PackageManagers
  commands={{
    npm: "npm run dev",
    yarn: "yarn run dev",
    pnpm: "pnpm run dev",
    bun: "bun run dev",
  }}
/>

### Adding the Components
Once your HeroUI project is ready to develop, you can add individual components using the CLI. For example, to add a button component:

```bash
heroui add button
```

This command adds the Button component to your project and manages all related dependencies.

You can also add multiple components at once:

```bash
heroui add button input
```

Or you can add the main library `@heroui/react` by running the following command:

```bash
heroui add --all
```

If you leave out the component name, the CLI will prompt you to select the components you want to add.

```bash
? Which components would you like to add? › - Space to select. Return to submit
Instructions:
    ↑/↓: Highlight option
    ←/→/[space]: Toggle selection
    [a,b,c]/delete: Filter choices
    enter/return: Complete answer

Filtered results for: Enter something to filter

◯  accordion
◯  autocomplete
◯  avatar
◯  badge
◯  breadcrumbs
◉  button
◯  card
◯  checkbox
◯  chip
◯  code
```

</Steps>

## Manual Installation

If you prefer not to use the CLI, you may try either global installation or individual installation to set up HeroUI in your project:

### Global Installation

The easiest way to get started with HeroUI is to use the global installation, which means
that all the components are imported from a single package.

Follow the steps below to install all HeroUI components:

<Steps>

#### Install Packages

To install HeroUI, run one of the following commands in your terminal:

<PackageManagers
  commands={{
    npm: "npm install @heroui/react framer-motion",
    yarn: "yarn add @heroui/react framer-motion",
    pnpm: "pnpm add @heroui/react framer-motion",
    bun: "bun add @heroui/react framer-motion"
  }}
/>

#### Hoisted Dependencies Setup

<Blockquote color="primary">
**Note**: This step is only for those who use `pnpm` to install. If you install HeroUI using other package managers, you may skip this step.
</Blockquote>

If you are using pnpm, you need to add the following line to your `.npmrc` file to hoist our packages to the root `node_modules`.

```bash
public-hoist-pattern[]=*@heroui/*
```

After modifying the `.npmrc` file, you need to run `pnpm install` again to ensure that the dependencies are installed correctly.

#### Tailwind CSS Setup

HeroUI is built on top of Tailwind CSS, so you need to install Tailwind CSS first. You can follow the official
[installation guide](https://tailwindcss.com/docs/installation/using-vite) to install Tailwind CSS. 

<Blockquote color="primary">
**Note**: If you are using pnpm and monorepo architecture, please make sure you are pointing to the ROOT `node_modules`
</Blockquote>

Then you need to create `hero.ts` file

```ts
// hero.ts
import { heroui } from "@heroui/react";
export default heroui();
```

and add  the following code to your main css file:

```css
@import "tailwindcss";
@plugin './hero.ts';
/* Note: You may need to change the path to fit your project structure */
@source '../../node_modules/@heroui/theme/dist/**/*.{js,ts,jsx,tsx}';
@custom-variant dark (&:is(.dark *));
```

#### Provider Setup

It is essential to add the `HeroUIProvider` at the `root` of your application.

```jsx
import * as React from "react";

// 1. import `HeroUIProvider` component
import {HeroUIProvider} from "@heroui/react";

function App() {
  // 2. Wrap HeroUIProvider at the root of your app
  return (
    <HeroUIProvider>
      <YourApplication />
    </HeroUIProvider>
  );
}
```

</Steps>

### Individual Installation

HeroUI is also available as individual packages. You can install each package separately. This
is useful if you want to reduce the size of your CSS bundle as it will only include styles for the components
you're actually using.

<Blockquote color="primary">
**Note**: JavaScript bundle size will not change due to tree shaking support in HeroUI.
</Blockquote>

Follow the steps below to install each package separately:

<Steps>

#### Install Core Packages

Although you can install each package separately, you need to install the core packages first
to ensure that all components work correctly.

Run one of the following commands in your terminal to install the core packages:

<PackageManagers
  commands={{
    npm: "npm install @heroui/theme @heroui/system framer-motion",
    yarn: "yarn add @heroui/theme @heroui/system framer-motion",
    pnpm: "pnpm add @heroui/theme @heroui/system framer-motion",
    bun: "bun add @heroui/theme @heroui/system framer-motion"
  }}
/>

#### Install Component

Now, let's install the component you want to use. For example, if you want to use the
[Button](/docs/components/button) component, you need to run one of the following commands
in your terminal:

<PackageManagers
  commands={{
    npm: "npm install @heroui/button",
    yarn: "yarn add @heroui/button",
    pnpm: "pnpm add @heroui/button",
    bun: "bun add @heroui/button"
  }}
/>

#### Hoisted Dependencies Setup

<Blockquote color="primary">
**Note**: This step is only for those who use `pnpm` to install. If you install HeroUI using other package managers, you may skip this step.
</Blockquote>

If you are using pnpm, you need to add the following line to your `.npmrc` file to hoist our packages to the root `node_modules`.

```bash
public-hoist-pattern[]=*@heroui/*
```

After modifying the `.npmrc` file, you need to run `pnpm install` again to ensure that the dependencies are installed correctly.

#### Tailwind CSS Setup

TailwindCSS setup changes a bit when you use individual packages. You only need to add the
styles of the components you're using to your `tailwind.config.js` file. For example, for the
[Button](/docs/components/button) component, you need to add the following code to your
`tailwind.config.js` file:

```js
// tailwind.config.js
const {heroui} = require("@heroui/theme");

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    // single component styles
    "./node_modules/@heroui/theme/dist/components/button.js",
    // or you can use a glob pattern (multiple component styles)
    './node_modules/@heroui/theme/dist/components/(button|snippet|code|input).js'
  ],
  theme: {
    extend: {},
  },
  darkMode: "class",
  plugins: [heroui()],
};
```

#### Provider Setup

It is essential to add the `HeroUIProvider` at the `root` of your application.

```jsx
import * as React from "react";

// 1. import `HeroUIProvider` component
import {HeroUIProvider} from "@heroui/system";

function App() {
  // 2. Wrap HeroUIProvider at the root of your app
  return (
    <HeroUIProvider>
      <YourApplication />
    </HeroUIProvider>
  );
}
```

#### Use the Component

Now, you can use the component you installed in your application:

```jsx
import * as React from "react";
import {Button} from "@heroui/button";

function App() {
  return (
    <Button>Press me</Button>
  );
}
```
</Steps>

## Framework Guides

HeroUI is compatible with your preferred framework. We have compiled comprehensive, step-by-step tutorials for the following frameworks:

<Frameworks />
